Puya PY32F MCU support by burgrp · Pull Request #5106 · tinygo-org/tinygo

burgrp · 2025-12-02T15:35:12Z

Hi, this is a port of of Puya PY32F super-cheap micro-controllers.
There are two new boards and supported (available on Aliexpress) for PY32F030 and PY32002b.
PY32F030 and PY32002b are supported, PY32F002a and PY32F071 will follow.
It follows the STM32 SVD pattern - there's a small TinyGo SVD repository dependent on Rust py32-rs repo. The repository is here: https://github.com/burgrp/py32-svd . I think it would be worth to move it to tinygo-org.

deadprogram · 2025-12-12T08:24:26Z

Hello @burgrp thank you for working on this.

Have you seen this page?
https://tinygo.org/docs/guides/contributing

I think you will find it helpful. 😸

deadprogram · 2025-12-13T18:53:43Z

@burgrp I have switched the branch for this PR to dev branch as mentioned here:
https://tinygo.org/docs/guides/contributing/#how-to-use-our-github-repository

Can you please rebase it against the latest dev so it can run all of the latest tests?
Also I made a few comments.

Planning on ordering a few of these myself, thanks for working on it!

b0ch3nski · 2026-01-27T16:53:01Z

@burgrp You are updating bdwgc submodule which is probably not something you meant to do - this breaks a lot of stuff 🔥

burgrp · 2026-01-27T19:04:18Z

You are right... I will fix it and hopefully it will be possible to merge the PR.

burgrp · 2026-02-13T19:51:23Z

@b0ch3nski , the sub-module issue is fixed, all checks are passing

b0ch3nski · 2026-02-15T12:22:11Z

Thanks! I think now there is some unrelated change also in net submodule 😬

deadprogram · 2026-02-15T13:56:07Z

@b0ch3nski looks that way to me as well: https://github.com/tinygo-org/tinygo/pull/5106/changes#diff-d7ea94295bc068e99e5edeacb50734849fb40d5aa39cbc68be5e55c0d90bd60a

@burgrp one other thing that is needed is to add something to the smoketests to show that at least everything can build. Someplace appropriate in here, please: https://github.com/tinygo-org/tinygo/blob/dev/GNUmakefile#L567-L989

burgrp · 2026-02-21T20:20:00Z

@b0ch3nski , @deadprogram smoketests added, net module update reverted

deadprogram · 2026-02-24T10:45:59Z

+	return uint8(p) & 0x0F
+}
+
+func (p Pin) getPort() (*py32.GPIO_Type, uint8) {


Better to use unsafe.Add() if you must. Probably even better to use a switch to avoid possible errors.

deadprogram · 2026-02-24T10:52:16Z

+	switch config.Mode {
+
+	case PinInputFloating:
+		port.MODER.ReplaceBits(gpioModeInput, gpioModeMask, pos)


I have not installed/run the gen-device-py32 yet, but I assume there are probably some functions like SetMODERInput() that are being generated. Using these are usually preferable, to avoid possible bugs from setting unexpected bits.

Unfortunately there is no SetMODERInput() generated. These helper functions are generated in form SetMODER_MODE0()...SetMODER_MODE15(), which are quite useless for parametric access.
I've fixed the machine constants to use the svd pin0 generated constants e.g.:
gpioModeOutput = py32.GPIO_MODER_MODE0_Output
so there is at least some binding to svd values.

deadprogram · 2026-02-24T10:52:21Z

+const PinInput PinMode = PinInputFloating
+
+const (
+	gpioModeInput     = 0


Are any of these being generated from the SVD file already? See comment below.

See my comment above.

deadprogram · 2026-02-24T10:53:23Z

+// peripheral clock frequency.
+func InitSerialWithClock(clockHz uint32) {
+	py32UARTClockHz = clockHz
+	//Serial.ConfigureWithClock(UARTConfig{}, clockHz)


Commented line?

deadprogram · 2026-02-24T10:55:39Z

+	py32.RCC.SetICSCR_HSI_FS(py32.RCC_ICSCR_HSI_FS_Freq24MHz)
+
+	ConfigureSystemTimer(24_000_000)
+	machine.InitSerial()


This perhaps needs to be moved into an init() function?

See #5200 (comment)

deadprogram · 2026-02-24T10:55:59Z

+  ],
+  "build-tags": [
+    "embedfire_py32f002b",
+		"default_uart_pins"


Formatting, please.

deadprogram · 2026-02-24T10:59:04Z

This is getting exciting @burgrp thank you so much for working on it! We were discussing during our TinyGo monthly meeting last night ❤️

I made some comments, hopefully @soypat and others can also take a look.

soypat · 2026-02-24T19:51:33Z

I've taken a look and have some reservations on exported API chosen. I'd like to better understand how we define APIs in machine package to understand if the exported functions implemented here match with what the rest of TinyGo does. Basically working on getting something like go doc -tags=rp2040 machine to work (which it does not currently)

soypat · 2026-02-25T15:38:04Z

I vibe coded a tool to help us understand the tinygo APIs better. I'll invite you all to check it out to understand what our APIs look like in TinyGo #5224

soypat

Running tgdoc I've found what look like discrepancies with usual TinyGo API.

You can browse our APIs by running go run ./cmd/tgdoc -http=:18080 ../tinygo/targets ../tinygo/src/machine given tinygodoc shares tinygo parent directory
https://github.com/tinygo-org/tinygodoc

soypat · 2026-03-02T13:07:02Z

+
+// ConfigureWithClock initializes the UART using the provided peripheral clock
+// frequency (in Hz). This avoids assuming a fixed MCU clock.
+func (uart *UART) ConfigureWithClock(config UARTConfig, clockHz uint32) error {


can we replace clockHz with CPUFrequency() internal call to Configure?

soypat · 2026-03-02T13:08:13Z

+
+// InitSerialWithClock configures the default Serial using the supplied
+// peripheral clock frequency.
+func InitSerialWithClock(clockHz uint32) {


Same as above, use CPUFrequency(). It is standard tinygo API, present on 160 targets.

soypat · 2026-03-02T13:08:45Z

+}
+
+// Configure pin for use by UART
+func ConfigureUARTPin(pin Pin, af uint8) {


Shouldn't this be Pin.Configure followed by an SetAltFunc? (is it really necessary to export this?)

Or unexport it if it is expected to only be called internally for UART configuration

You are right, cleaned up to just Pin.Configure+SetAltFunc.
This needs to be exported, because other boards may need explicit call for non-default UART pins.

Non default pins can be configured with the UARTConfig struct. Please unexport this.

Unfortunately it can't be configured using UARTConfig on PY32F. We need to pass the AF parameter somehow.

However, I will try to fix it somehow...

The function removed.

soypat · 2026-03-04T03:50:58Z

+func SetCPUFrequency(frequency uint32) {
+	CPUFrequencyHz = frequency
+}


This is a very confusing API- it does not actually change the frequency. Prefer unexporting it and either linking with //go:linkname compiler directive from runtime package or setting as constant at build time.

I agree - the function is removed. The variable CPUFrequencyHz still needs to be exported to allow clock change from user code.

Why do you want to allow changing CPU frequency from user code?

This API does not exist yet in TinyGo, we'd likely need to discuss the best design going forward if we are to add it

For two simple reasons (correct me if I'm not seeing something):

TinyGo comes with a finite set of supported dev boards. In practice, final product boards differ, so they may need other setting.

There may be application which need to set clock dynamically, e.g. to save energy.

https://github.com/orgs/tinygo-org/discussions/5239

Yes, I need that for one of my projects. Thanks for being open to discuss it!

I'd hate for this to stay in a stale state while we discuss the CPUFrequency API. Could you implement CPU frequency API on your side and test things and let us know how your experimentation goes?

This API is still very unintuitive because it does exactly none of what it says it does. Calling this function does not actually do anything yet documentation and the name state otherwise. Either remove the CPU setting frequency API or figure out how to include it in an intuitive way.

Consider we want new users of the PY32 with TinyGo to have a smooth experience and not be confused as to why the CPU frequency has not changed after calling the function that says it changes CPU frequency. If need be have this function do all the reinitialization of all peripherals to fulfill the objective.

The function was removed - no SetCPUFrequency anymore.

burgrp · 2026-04-28T22:15:55Z

@soypat I'm using this PY32F port already for few firmware projects. No change was needed for a month or two, so the code seems to be stable. What do you think about merging it?

soypat · 2026-05-03T13:28:33Z

+func SetCPUFrequency(frequency uint32) {
+	CPUFrequencyHz = frequency
+}


This API is still very unintuitive because it does exactly none of what it says it does. Calling this function does not actually do anything yet documentation and the name state otherwise. Either remove the CPU setting frequency API or figure out how to include it in an intuitive way.

Consider we want new users of the PY32 with TinyGo to have a smooth experience and not be confused as to why the CPU frequency has not changed after calling the function that says it changes CPU frequency. If need be have this function do all the reinitialization of all peripherals to fulfill the objective.

soypat · 2026-05-03T13:32:21Z

+}
+
+// Configure pin for use by UART
+func ConfigureUARTPin(pin Pin, af uint8) {


Non default pins can be configured with the UARTConfig struct. Please unexport this.

soypat · 2026-05-03T15:14:35Z

+	for uart.Bus.SR.Get()&py32.USART_SR_TXE == 0 {
+	}


I missed these hot loops. can we take measures to prevent runaway spinning?

https://tinygo.org/docs/guides/driver-design/#hot-loops

soypat · 2026-05-03T15:14:48Z

+	for uart.Bus.SR.Get()&py32.USART_SR_TC == 0 {
+	}


this hot loop too

soypat · 2026-05-03T15:16:53Z

+func (p Pin) SetAltFunc(af uint8) {
+	port, pin := p.getPort()
+	if pin >= 8 {
+		port.AFRH.ReplaceBits(uint32(af), 0xF, (pin%8)*4)
+	} else {
+		port.AFRL.ReplaceBits(uint32(af), 0xF, (pin%8)*4)
+	}
+}


I'm still very confused as to why these APIs are here. I am not familiar with the py32. Maybe documenting them here would clarify to me and future users how to use Altfuncs on the py32 and also maybe give me clarity to suggest alternative APIs?

This is how you configure a pin for an alternative function, such as UART RX or ADC IN.

Documentation added.

OK, I think we can approach the UART config of pins like RP2040 does it:

type pinFunc: https://github.com/tinygo-org/tinygo/blob/dev/src/machine/machine_rp2_gpio.go#L59

setPinFunc: https://github.com/tinygo-org/tinygo/blob/dev/src/machine/machine_rp2_gpio.go#L145-L152

pinfunc definitions for RP2040:

tinygo/src/machine/machine_rp2_2040.go

Lines 99 to 124 in 1a1506e

fnJTAG pinFunc = 0

fnSPI pinFunc = 1 // Connect one of the internal PL022 SPI peripherals to GPIO

fnUART pinFunc = 2

fnI2C pinFunc = 3

// Connect a PWM slice to GPIO. There are eight PWM slices,

// each with two outputchannels (A/B). The B pin can also be used as an input,

// for frequency and duty cyclemeasurement

fnPWM pinFunc = 4

// Software control of GPIO, from the single-cycle IO (SIO) block.

// The SIO function (F5)must be selected for the processors to drive a GPIO,

// but the input is always connected,so software can check the state of GPIOs at any time.

fnSIO pinFunc = 5

// Connect one of the programmable IO blocks (PIO) to GPIO. PIO can implement a widevariety of interfaces,

// and has its own internal pin mapping hardware, allowing flexibleplacement of digital interfaces on bank 0 GPIOs.

// The PIO function (F6, F7) must beselected for PIO to drive a GPIO, but the input is always connected,

// so the PIOs canalways see the state of all pins.

fnPIO0, fnPIO1 pinFunc = 6, 7

// General purpose clock inputs/outputs. Can be routed to a number of internal clock domains onRP2040,

// e.g. Input: to provide a 1 Hz clock for the RTC, or can be connected to an internalfrequency counter.

// e.g. Output: optional integer divide

fnGPCK pinFunc = 8

// USB power control signals to/from the internal USB controller

fnUSB pinFunc = 9

fnNULL pinFunc = 0x1f

fnXIP pinFunc = 0

uart config of pins: https://github.com/tinygo-org/tinygo/blob/dev/src/machine/machine_rp2_uart.go#L53-L57

what do you think?

FYI: The exported API is PinMode:

tinygo/src/machine/machine_rp2_2040.go

Lines 36 to 46 in 1a1506e

PinOutput PinMode = iota

PinInput

PinInputPulldown

PinInputPullup

PinAnalog

PinUART

PinPWM

PinI2C

PinSPI

PinPIO0

PinPIO1

deadprogram · 2026-08-28T09:20:51Z

Reviewed the five new commits. The branch was rebased, so I compared f6212fc5 against 733cd226.

Verified as fixed

All four items are done, and two are solved better than I suggested.

1. The misleading HSI constant. Fixed upstream in the SVD, which is the right layer. The submodule moved to f540a907 and now carries one named value per family. Freq24MHz is 3 on F032 and 4 on the other default path families. Because the value is per family, py32_hsi_fs_literal3 disappears completely and py32f001xx also drops py32_hsi_fs_literal4. I checked all 41 SVDs. Every family on the default path defines Freq24MHz, and the four that do not are exactly the families on other paths.

2. py32.CPU == "CM4". Back to the py32_no_hsi_fs build tag, so the machine and runtime packages read one source.

3. 1 << 14. py32.RCC_APBENR2_USART1EN is back on the default path, the literal is isolated behind py32_usart1_clock_literal, and the comment that explains the exception is restored.

4. Mask used as a value. UART_CR1_M_Char8Bits was added to the T020 SVD and is now used.

CI. smoketest-py32 is defined in make/smoketest.mk, added to SMOKETEST_SUBTARGETS, and wired into a shard. All checks pass. The new shard runs in 6m36s, which is in line with the other three.

One new comment

py32f001cxx and py32f002cxx still carry py32_hsi_fs_literal4, and their SVDs under declare the HSI_FS field.

py32f001cxx        HSI_FS [16:16]   1 bit
py32f002cxx        HSI_FS [17:16]   2 bits
all other families HSI_FS 3 bits

In both SVDs LSI_TRIM starts at bit 19, so bit 18 is unclaimed. The real field is very likely [18:16], which agrees with the removed comment about F002C shifting its bits by the LSI_TRIM position.

Writing 4 into a field declared as 1 or 2 bits still gives the right result today, but only by accident. The generated setter is reg &^ Mask | value << Offset and it never masks value, so 4 << 16 sets bit 18, which is the top bit of the real field. On F002C that lands on 0b100 correctly. On F001C bit 17 sits outside the declared mask and stays unchanged, so the result is correct only while bit 17 is zero.

You are already patching field metadata upstream. Correcting these two bitRange values to [18:16] and adding Freq24MHz would let both families drop py32_hsi_fs_literal4 and delete runtime_py32_hsi_literal4.go and its tag, the same way you just did for F032 and F001.

On the file count

The earlier comments 2 and 3 traded file count for correctness and put three files back. The count went from 36 to 33 and then to 35, so the total across both rounds is 36 to 35. That moves the wrong way against the earlier request to reduce build tag variants. The SVD fix above would bring it to 34 and remove the last HSI variant.

Still open

Pin.SetAltFunc is still exported, but since the same function is already being exported by STM32, I think we should allow here. @soypat what do you think?
flush() still drops its timeout without an error.
uartYield calls gosched(), which is a no-op because every PY32 target sets "scheduler": "none". Only the retry count bounds the loop.

Fixing the constants in the SVD instead of working around them in Go is the right way to do it. It removes a whole class of problem.

burgrp · 2026-08-28T09:28:09Z

I have rebased and resolved that makefile refactoring.

@soypat , I think the last unresolved point is whether Pin.SetAltFunc should remain exported. My position is to keep it exported, for two reasons:

First, STM32 already exposes the same kind of functionality, so this seems consistent with existing practice and may be a candidate for a common API in the future.

Second, this is a practical requirement for my current project. The generic HAL is valuable, but it cannot cover every peripheral and pin-mapping combination across all MCU vendors and families. There will always be cases where an application needs a low-level escape hatch to select the alternate function required by a specific peripheral - some families have exotic peripherals like 7-segment LED driver or motor MOSFET drivers.

For those reasons, I need SetAltFunc to remain accessible to user code. I am happy to improve its naming or documentation if that would address concerns about how this low-level API should be presented.

deadprogram · 2026-08-28T17:59:14Z

This is one of the exports of SetAltFunc() elsewhere in the machine package:

https://github.com/tinygo-org/tinygo/blob/dev/src/machine/machine_stm32_moder_gpio.go#L165

soypat

Looks good. SetAltFunc is fine. We tend to export non-standard low level APIs in the rest of TinyGo so the harm is not too bad. I do have a question regarding the switch/vs table approach: did you try both out?

soypat · 2026-08-28T18:04:43Z

+
+// PY32F003 datasheet tables 3-6 through 3-8 and PY32F030 datasheet
+// tables 3-1 through 3-3.
+func uartPinAF(uartNum uint8, pin Pin, tx bool) (uint8, bool) {


was this more effective than the table approach?

Yes, it was. It wins on flash, costs no more RAM, and gives LLVM better opportunities to eliminate irrelevant branches for constant UART/pin configurations.

Anyway, thanks for approving the SetAltFunc. Don't worry, I'm still thinking about the full support of all peripherals through PinMode as you suggested. However, it's a substantial piece of work, which could be perhaps done as a future feature. It's not only about the code optimization, but also about how to extract all that information reliably from all the datasheets and generate code from it.

deadprogram · 2026-08-29T06:38:56Z

Thank you very much for all the work on this @burgrp and to @soypat & @b0ch3nski for all the reviews/feedback to help get it in. Now squash/merging!

deadprogram changed the base branch from release to dev December 13, 2025 18:43

deadprogram reviewed Dec 13, 2025

View reviewed changes

Comment thread targets/embedfire-py32f002b.json Outdated

deadprogram reviewed Dec 13, 2025

View reviewed changes

Comment thread targets/embedfire-py32f002b.json Outdated

deadprogram reviewed Dec 13, 2025

View reviewed changes

Comment thread targets/embedfire-py32f030.json Outdated

burgrp force-pushed the py32 branch from 8e14179 to fa6d383 Compare December 15, 2025 19:29

burgrp force-pushed the py32 branch from 84756c5 to 7fa20c4 Compare January 7, 2026 00:07

deadprogram reviewed Feb 24, 2026

View reviewed changes

soypat reviewed Mar 2, 2026

View reviewed changes

soypat reviewed Mar 4, 2026

View reviewed changes

soypat requested changes May 3, 2026

View reviewed changes

soypat reviewed May 3, 2026

View reviewed changes

burgrp added 22 commits August 28, 2026 10:10

machine/py32: report the configured CPU frequency

ed97c2b

machine/py32: use unsafe.Add for GPIO ports

882e08c

machine/py32: bound and yield UART polling

78166de

machine/py32: configure UART pins from UARTConfig

c635bdd

build: use the current PY32 SVD repository URL

ad9002d

test: cover PY32 UART register layouts

98a2d1b

machine/py32: restore dynamic CPU frequency tracking

fe40cc7

machine/py32: share the USART TX-ready bit

3d0ec81

targets/py32: scale system stacks with RAM

1792004

machine/py32: keep clock state internal

d7a1bda

targets/py32: normalize generated metadata

dbab89b

machine/py32: normalize GPIO configuration

5fb9fce

machine/py32: fix T020 UART setup

fdfcbe9

machine/py32: reduce clock variant files

aa5d05d

machine/py32: clean up UART variants

189ed92

machine/py32: decouple UART clock capability

06a523e

lib/py32-svd: use organization repository

f6212fc

runtime/py32: name 24MHz HSI encodings

2432011

machine/py32: derive startup clock from capability

10228f6

machine/py32: use generated USART clock mask

381d45f

machine/py32: name T020 8-bit UART mode

a3c9946

ci: include PY32 in sharded smoke tests

733cd22

burgrp force-pushed the py32 branch from f9fdc9e to 733cd22 Compare August 28, 2026 08:18

runtime: remove PY32 HSI frequency workaround

dcbcdfa

soypat approved these changes Aug 28, 2026

View reviewed changes

deadprogram merged commit b420a8b into tinygo-org:dev Aug 29, 2026
24 checks passed

	fnJTAG pinFunc = 0
	fnSPI pinFunc = 1 // Connect one of the internal PL022 SPI peripherals to GPIO
	fnUART pinFunc = 2
	fnI2C pinFunc = 3
	// Connect a PWM slice to GPIO. There are eight PWM slices,
	// each with two outputchannels (A/B). The B pin can also be used as an input,
	// for frequency and duty cyclemeasurement
	fnPWM pinFunc = 4
	// Software control of GPIO, from the single-cycle IO (SIO) block.
	// The SIO function (F5)must be selected for the processors to drive a GPIO,
	// but the input is always connected,so software can check the state of GPIOs at any time.
	fnSIO pinFunc = 5
	// Connect one of the programmable IO blocks (PIO) to GPIO. PIO can implement a widevariety of interfaces,
	// and has its own internal pin mapping hardware, allowing flexibleplacement of digital interfaces on bank 0 GPIOs.
	// The PIO function (F6, F7) must beselected for PIO to drive a GPIO, but the input is always connected,
	// so the PIOs canalways see the state of all pins.
	fnPIO0, fnPIO1 pinFunc = 6, 7
	// General purpose clock inputs/outputs. Can be routed to a number of internal clock domains onRP2040,
	// e.g. Input: to provide a 1 Hz clock for the RTC, or can be connected to an internalfrequency counter.
	// e.g. Output: optional integer divide
	fnGPCK pinFunc = 8
	// USB power control signals to/from the internal USB controller
	fnUSB pinFunc = 9
	fnNULL pinFunc = 0x1f

	fnXIP pinFunc = 0

	PinOutput PinMode = iota
	PinInput
	PinInputPulldown
	PinInputPullup
	PinAnalog
	PinUART
	PinPWM
	PinI2C
	PinSPI
	PinPIO0
	PinPIO1

Uh oh!

Uh oh!

Conversation

burgrp commented Dec 2, 2025

Uh oh!

deadprogram commented Dec 12, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

deadprogram commented Dec 13, 2025

Uh oh!

b0ch3nski commented Jan 27, 2026

Uh oh!

burgrp commented Jan 27, 2026

Uh oh!

burgrp commented Feb 13, 2026

Uh oh!

b0ch3nski commented Feb 15, 2026

Uh oh!

deadprogram commented Feb 15, 2026

Uh oh!

burgrp commented Feb 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deadprogram commented Feb 24, 2026

Uh oh!

soypat commented Feb 24, 2026

Uh oh!

soypat commented Feb 25, 2026

Uh oh!

soypat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soypat Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

burgrp Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

soypat Mar 2, 2026 •

edited

Loading

burgrp Mar 3, 2026 •

edited

Loading